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The tollowing errata apply to the Sniffer Network Analyzer: Protocol Interpreter Development Kit. 


1. On page 1—, under the heading, “Writing a Protocol Interpreter,” the manual informs you that you will need to obtain 
Version 6.00AX of the Microsoft C compiler. This compiler and the necessary library files are now included as part of 
the Protocol Interpreter Development Kit. You no longer need to obtain them separately. 


t 


On page 1-6, Figure 1-1 lists the files provided with the Protocol Interpreter Development Kit. In addition to the files 
listed, the following files are also provided as part of the Microsoft 6.0OAX C Compiler: 


Files Provided With Microsoft 6.00 AX C Compiler 
CL.EXE | CL.MSG | CIL.EXE 


{ 


LLIBCE.LIB C1.ERR | C23.ERR 
CL.ERR | C2L.EXE C3L.EXE 


3. On page 1-7, under the heading, “Installing the Microsoft C Compiler,” the document gives instructions for installing 
the compiler. The Protocol Interpreter Development Kit now includes all the tools required to write new protocol 
wiérpreters and build new Sniffer analyzers, including the compiler and the library. You will act acea to install the 
Microsoft C Compiler because it is already installed with the Protocol Interpreter Development Kit. 


4. On page 1-31, Step 4 of the procedure, “To build a new Sniffer analyzer,” lists several changes that should be made to 
the BUILDSNF-.BAT file. The necessary files for Microsoft C 6.00AX are now distributed with the Protocol Interpreter 
Development Kit. If you are using the compiler supplied with your Protocol Interpreter Development Kit, then the 
BUILDSNF-.BAT file is already set correctly. You will not need to change the BUILDSNF.BAT file unless you are 
using a custom development environment. If this is the case, you will need to change the lines in BUILDSNF.BAT that 
set the three variables listed in Step 4 on page 1-31. 


5. To use the Protocol Interpreter Development Kit, you must add the following line to the CONFIG.SYS file of the 
Sniffer Network Analyzer: 


DEVICE=C: \DOS\HIMEM. EXE 


Note: If your Sniffer Network Analyzer has less than 32MB of RAM, you must remove the above command line 
before starting the Sniffer Network Analyzer. 


6. Before using the Microsoft C compiler, type the following command: 
SET PATH=C:\DOS;C:\TOOLS; C: \TOOLS\C6Q2AX 
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Preface 


About This Manual 


Welcome to the Protocol Interpreter Development Kit. This manual explains the 
rules and conventions for writing programs that extend the Sniffer Network 


Analyzer’s ability to interpret protocols. 


Navigational Aids Used in This Manual 


=> 
® 


KI 


a 


Ke 


This manual uses icons in the margin to help you locate important information 
as explained below: 


IMPORTANT INFORMATION. Next to this icon is information that is 
especially important; you should be certain to read it carefully before you 
proceed. 


WARNING. Next to this icon are instructions that you must follow to avoid 
possible damage to data files, program files, or hardware devices. © 


PROCEDURE. Next to this icon is a series of steps for accomplishing a particular 
task. 


Manuals for the Sniffer Network Analyzer 


Two types of manuals accompany the Sniffer Network Analyzer. The primary 
manuals, which include this manual, describe the system’s normal operations; 
the supplementary manuals describe the programs that configure and test the 
system's various hardware and software components for troubleshooting. The 
actual manuals in your shipment depend on the system configuration. 


The following table describes the primary manuals. 


For Information On... Read... 


Installing and configuring the Sniffer Network | Sniffer Network Analyzer: 


Analyzer. Installation Guide 

Operating the analysis functions on an Expert Sniffer Network Analyzer 
Ethernet or Token-Ring network. Operation 

Operating the monitor functions on an 

Ethernet network. Sniffer Network Analyzer: 

Using the monitor features effectively to | Ethernet Monitor Operations. 


detect network abnormalities. 
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For Information On... Read... 


Operating the monitor functions on a token 


ring network. 


Sniffer Network Analyzer: 


Using the monitor features effectively to Token-Ring Monitor Operations 
detect network abnormalities. 


Various network and protocol types. 


Sniffer Network Analyzer: 
Network and Protocol Reference 


Conventions Used in This Manual 


Special Notations 


Terminology 


Other Sources of Information 


vi 


The following describes the conventions used in this manual: 


Bold 


UPPERCASE 


Screen font 


Menu options are in bold type. For example: 
Move to Display, and press Enter. 


Filenames and commands you type at a DOS prompt are 
in uppercase. For example: 


Modify the AUTOEXEC.BAT file if necessary. To 
duplicate the file, use the COPY command. 


ocreen messages are printed in monospaced font. For 
example: 


If a monitoring session is in progress, the following 
message appears: 


You must stop monitoring before you can use this feature. 


Hexadecimal numbers in the manual are followed by “(hex)”; numbers without | 
any notations are decimal. For example, “The maximum number of stations is 
75. The default memory address is D8000 (hex).” 


The term “analyzer” refer to the software application that runs on the Sniffer 


Network Analyzer. 


Network General Corporation (NGC) provides other sources of information 
that can help you become familiar with the Sniffer Network Analyzer. 


(Cenc 


Other Sources of Information . 


On-Line Help 


After highlighting an item in the analyzer menu, you can see a phrase or 
sentence in a panel near the bottom of the screen. It explains the meaning of the 
highlighted item. To obtain general information about a particular feature of the 
Sniffer Network Analyzer, press F1 at any time within the menus of the 
analyzer application. A window containing a list of topics opens. 


Technical Support 


A toll-free number is available to obtain technical support for the Sniffer 
Network Analyzer. 


Phone for Network General’s Technical 


Support Department: (800) 395-3151 


FAX: (415) 327-9436 
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General 


Extending and Customizing Protocol 
Interpreters 


Overview 


This chapter describes the rules and conventions for writing programs that 
extend the Sniffer analyzer’s ability to interpret protocols. 


Network General Corporation (NGC) is constantly expanding the list of 
available protocol interpreters (PIs). Before writing your own PI, you should 
check with NGC to see what is currently available. 
To use this chapter, you need to be familiar with: 

¢ The general operation of the Sniffer analyzer. 


¢ The C programming language and the MS-DOS programming 
environment. 


¢ The general structure of network frames and the detailed structure of 
your protocol. 
This chapter is divided into three major sections: 


« An overview section that discusses what PIs do and how to install the 
tools you need to write new PIs. 


¢ A section on writing the C code that performs the necessary PI 
functions. 


¢ A section on integrating the PI that you have written into the existing 
Sniffer analyzer code. 


You should read this chapter before writing a new PI. 


What Does a Protocol Interpreter Do 


A PIis a routine (or set of routines) that, when invoked, receives a pointer to 
data somewhere within a frame. The interpreter has four tasks: 


¢ Generate one or more short text lines to display in the summary view 
for its protocol. 


* Generate lines for the detail view and highlight the appropriate hex 
view characters. 


* Call the PIs for embedded protocols, if any. 


¢ Supply new symbolic names discovered within the protocol’s data. 
There are two types of PIs: demultiplexed and embedded. A demultiplexed PI 
is called directly from the Sniffer analyzer, based on the frame’s identifying 


code. (Depending on the network, that may be its Ethertype, its ARCNET 
system code, its 802.2 LLC DSAP, and so on.) 
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Anembedded PlIis called by another PI to interpret a protocol nested at a higher 
level. An embedded PI may be shared. It may be called from several other PIs 
and may be used at different protocol levels. 


Writing a Protocol Interpreter 


In order to write new protocol interpreters, you need: 


¢ the PI Development Kit from NGC and installed in your Sniffer or in a 
IBM-PC compatible. 


¢ Version 6.00AX of the Microsoft C compiler from Microsoft 
Corporation installed with the PI Development Kit. 


Porting Current Protocol Interpreters 


If you wrote one or more protocol interpreters for previous versions of the 
Sniffer analyzer and want to re-use them in the new version, refer to this section; 
otherwise, go to the section “Installing the PI Development Kit” on page 1-5. 


To integrate your existing protocol interpreter into the new version of the 
Sniffer analyzer: 


1. Install the PI Development Kit. See the section “Installing the PI 
Development Kit” on page 1-5. 


‘KD 
OY 


2. Install version 6.00AX of the Microsoft C compiler. See the section 
“Installing the Microsoft C Compiler” on page 1-7 for information on 
suggested options. 


3. Move the source code for your PI to the directory where the PI 
Development Kit is installed. 


4. Check that your PI is named interp <protocol_name> and that its data 
structure is named pi data <protocol_ name>, where <protocol name> is the 
name of the protocol your Pl interprets. For more information about this, 
refer to the section “Registering Protocol Interpreters” on page 1-28. 


5. If your protocol interpreter uses the pi_get frame or pi_invoke pis 
functions, you should be aware that although NGC supports these 
functions, NGC-written protocol interpreters no longer use them. Read 
the section “Dependencies on Other Frames” on page 1-24 and modify 
your protocol interpreter to use the techniques NGC recommends. 


6. Asprintf function is delivered with the PI Development Kit. It differs 
from the sprintf function in the standard C library in a number of ways 
that simplifies writing protocol interpreters and makes them more 
robust. NGC recommends that you refer to the section “Sprintf Function 
in the PI Development Kit” on page 1-17 and use its features. 


7. Read the section “Registering Protocol Interpreters” on page 1-28 and 
modify the new INITPL.C to register your protocol interpreter. 


8. Follow the directions in the section “Building a New Sniffer Analyzer” 
on page 1-31. 


Writing a Protocol Interpreter 


Installing the PI Development Kit 


You can install the PI Development Kit on your Sniffer analyzer or on a system 
capable of running version 6.00AX of the Microsoft C compiler. If you chose to 
install the kit on another system, you will need a 386 or faster CPU with at least 
1-Mbyte of extended memory. The advantages of running the PI Development 
Kit on a system other than your Sniffer analyzer are: 


¢ the compiler and linker may run faster on a different machine. 


¢ the PI Development Kit requires 8 Mb of disk space. 


The disadvantage is that you must test your new Sniffer analyzer on the Sniffer 
analyzer hardware; therefore, you must have some way of moving the linked 
executable from one machine to another. 


Note: If you develop your protocol interpreter on another machine, the linked 
executable may be larger than a floppy diskette; you may need either a data 
compression utility or a communications or network connection to transfer the 


executable. 
KI To install the PI Development Kit: 
OY 
1. Insert Disk 1 into drive A. 


2. Type a:install and press Enter. 


The installation process begins and installs all the tools, source files, 
libraries, and sample files into the \xxSNIFF\NEWPI directory, where | 
xx is the two-letter network abbreviation. 


If you install to a machine other than the Sniffer, the \xxSNIFF\NEWPI 
directory is created. You can relocate the files to any other directory you 
chose. 


3. Follow the instruction prompts to complete the installation process. 


Figure 1-1 lists the files in the PI Development Kit sub-directory. 
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Files 


INITPI1.H 
INITPI2.H 
INITPI.C 


MSG.H 
NETWORK.H 
PILH 
PISWITCH.H 
Pl_LOGIC.H 
PIFDECL.H 


BUILDSNF.BAT 
OVLINK.LNK 
OVLPIMAP.OBJ 
OVLUTIL.LIB 


OVPATCH.EXE - 


RTLINK.CFG 

RTLINK.DAT 

RTLINK.EXE 
RTLUTILS.LIB 


SAMPLE.C 
SAMPLE. xxC 


ATALK.H 
AT_PORTS.C 


SMB.H 
SMBGLOBE.H 
INTSMBO.C 


TCP.H 
TCPPORTS.C 


X25.H 
X25CALLS.C 
USERHDLC.C 


XWINEXT.C 


SNMP.H 
NETMGMT.C 


xxSNIFFC.LIB 
KS.LIB 
PICODE.LIB 
PISTRING.LIB 
RTPI.LIB 
SN_WFC.LIB 
XP.LIB 


Description 


Files for registering Pls. 


General “include” files. 


Tools for building Sniffer analyzer software. 


Source code of the sample PI. 


A capture file illustrating the sample PI. 


Files for embedding a PI within AppleTalk. 


Files for embedding a PI within SMBs. 


Files for embedding a PI within IP, TCP, and 
UDP. 


Files for embedding a PI within X.25 and 
HDLC. 


Files for embedding a PI within XWindows. 


Files for embedding new objects in SNMP. 


Libraries for building Sniffer analyzer 
software. 


Figure 1-1. PI Development Kit files. 
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Installing the Microsoft C Compiler 


The tools required to write new PIs and build new Sniffer analyzers, except for 
the Microsoft C compiler, are included in the PI Development Kit. The PI 
Development Kit only works with version 6.00AX of the Microsoft C Compiler. 


Follow the installation instructions provided by Microsoft. The Microsoft 
installation programs offer a long list of choices to install the compiler. Consider 
the following: 


¢ Install the DOS or the DOS-and-OS/2 versions (not the Windows 
version) of the compiler. This is the default option. 


¢ The directory in which you install the “bound executables” must be 
added to your DOS path so that the compiler can be found. 


¢ Install the LARGE model of the libraries. The default is to install only 
the SMALL model, which you will not need for PI development. 


¢ Assign the default names to the DOS libraries. 


¢ You do not need the programmer's workbench, mouse support, or 
on-line documentation. 


Coding a Protocol Interpreter 
The following sections describe how to write the C code for a protocol 
interpreter. 
Calling Conventions for Protocol Interpreters 
The Sniffer analyzer core code calls PIs using the following calling sequence: 
int bytes_interpreted; 


char *frame_ptr; /* Pointer to the frame data */ 
int frame_length; /* The length of the frame data starting at frame_ptr */ 


bytes interpreted = interp_protocol (frame_ptr, frame_length); 


The frame_ptr parameter points to the beginning of the data for the protocol 
within the physical frame. It skips previous protocol fields, including source 
and destination addresses, type fields, and any previously embedded protocol 
data. 


The Sniffer analyzer permits the user to request that frames be truncated as it 
captures them. It then records no more than a certain number of bytes for each 
frame and discards the rest. When the user selects truncation, frame_length is the 
length of the stored (truncated) data, and the global integer bytes_not_ present 
indicates how much additional frame data was received but not recorded. 


7 The following rule applies only to Ethernet, StarLAN, and token ring. Fora 
demultiplexed PI that is called for a particular LLC DSAP, frame ptr is the 
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address of the first byte of the information field. The information field 
immediately follows the source and destination SAPs and the control field. The 
SAP protocol interpreter is called for any frame with an information field, such 
as I, UI, or XID. It is not called for frames that do not contain information, such 
as RR or that do not contain higher-level protocol information, such as TEST or 
FRMR. 


The following rule applies only to Ethernet, StarLAN, and PC Network. For a 
demultiplexed PI that is called for a particular Ethertype, frame_ptr is the 
address of the first byte of the information field. The information field 
immediately follows the 2-byte Ethertype. 


The value returned from the PI is the number of bytes of frame data that it 
interpreted. The calling interpreter may use the returned value to decide 
whether any subsequent interpreters are to be called. If there is no more data left 
to interpret, simply return the initial value of frame_length. 


If the PI needs access to DLC or LLC header fields, or to the frame number, it 
may refer to the values of certain global static variables in which these are 
recorded. They are listed in Figure 1-2. 


Global Static Variable Purpose 


long pi_frame; The current frame number. 


| Pointer to DLC header starting with the 
i a first byte of the frame. 


For 802.3 networks, Ethernet, StarLAN, and Token ring: 


A pointer to the LLC header of the 


char sete ne aden frame, starting with the DSAP field. 


The type of the LLC frame; 
see the Ilc_xxx macros in pi.h. 


int lic_type; 
Figure 1-2. Global static variables available to the protocol interpreter. 
Any PI your PI calls to interpret embedded protocols should be invoked using 
the same calling convention. 


Protocol Interpreter Data Structure 


This structure is set up during the protocol interpreter registration process 
described later in this chapter. You should declare the data structure as an 
external in your protocol interpreter: 


extern’ struct *pi_data pi_data_your_protocol; 


The complete definition of this structure is contained in the file PI.H. The fields 
described below are the only ones relevant to your protocol interpreters. Each 
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field below is a “boolean,” in which the value 0 indicates “false” and 1 indicates 
Ml true. wy 


struct pi data { 
int do_sum; Generate summary lines? 
int do_int; Generate detail interpretation lines? 


int do_count; Generate only count of summary lines? 


int do_ names; Add symbolic station names? 


int recursive; Recursive call to get information for 
another frame? 


If do_sum is true, your protocol interpreter must generate a summary line. If 

do count is also true, then the Sniffer analyzer only needs a count of summary 
lines. Your protocol interpreter must allocate a summary line but need not 
actually write to it. 


If do int is true, your protocol interpreter must generate one or more detail 
lines. Note that if both summary and detail views are enabled, both do_sum and 
do _ int are true at the same time. 


If do names is true, the user has selected the Search for names menu option. 
Examine the frame data for embedded station names defined by the protocol. If 
any are found, call the add_station_name function, described in the section 
“Adding Symbolic Names to the Name Table” on page 1-20 to enter the names 
into the name table. 


The recursive flag is supported only for compatibility with previously written 
protocol interpreters. It is still supported, but it should not be used in new 
protocol interpreters. 


Your PI should call interpreters for any embedded protocols regardless of the 
flag settings. 


Generating Output from Protocol Interpreters 


Protocol interpreters generate output by asking the Sniffer analyzer core code 
for a buffer to write a summary or a detail line and then writing a string into that 
buffer. The following sections discuss enhancements to the sprintf function that 
allow you to generate output and a series of “PIF routines” that do most of the 
work. 


To generate a line for the summary view from within a PI, get the address of a 
line buffer by calling get_sum line: 


char *get_sum_line (pi_data_your_protocol); Returns a pointer to the line buffer 


struct pi_data *pi_data_your_protocol; Your protocol interpreter data structure 


Then move a character string (ending witha null) into the buffer provided using 
sprintf, strcpy, strcat or any other mechanism available in C. The length of the 
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string including the null must not exceed MAX_SUM_ LINE. For visual consistency of 
the displayed output, the summary line should begin with a 3-character 
identification of the protocol and a blank. 


Generating a line for the detail view is similar. However, the function to get the 
address of a line buffer also provides an optional offset and length that show 
where in the frame the information was found. This is used to highlight the hex 
field when the user selects the corresponding line of the detail view. 


char *get_int_line (pi_data_your_protocol, offset, length); /*Returns a pointer to the line */ 


/*buffer */ 


struct pi_data *pi_data_your_protocol; /*Your PI’s data structure. */ 


int offset; 


int length; 


The offset from the DLC header of the field that generated the 


interpretation line. You can calculate this using the global variable 
dlc_header that points to the DLC header as shown in Figure 1-2, or you 
can use pif_offset, another global variable, discussed in the next section. 


The length of the field, or 0 if no highlighting is desired. 


The string should be built in the supplied buffer. Its length, including the final 
null, must not exceed MAX_INT LINE. 


The version of sprintf included with the PI Development Kit will never write 
beyond the end of summary or detail line buffers. If you only use sprintf to write 
to these lines, you never need to check the length of your lines. 


In general, the Sniffer analyzer automatically scrolls the detail view so that the 
top line is the first line for the protocol that the user selected in the summary 
view. If you wish some other line of your protocol’s detail lines to scroll to the 
top, you may specify a negative offset when calling get_int_line. 


Your protocol interpreter should generate summary lines only when do _ sun is 
set to true in the PI data structure and should generate detail lines only when 
do_int is set to true. An error occurs if this is not done. 


The Protocol Interpreter Formatting Routines 


PIs may be written with no functions used other than those already described 
and those available in the standard C library. For fixed-format data, the simplest 
approach is often to write structure declarations and simply format summary 
and detail lines using the sprintf function in the standard C library. 


When data contains many variable-length or optional fields, however, using 
C-language structures becomes awkward. To address this problem, NGC 
provides a series of stream-oriented formatting utilities: 


* Protocol interpreter formatting (PIF) routines discussed in this section. 


* Sprintf function discussed in the section “Sprintf Function in the PI 
Development Kit” on page 1-17. 
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The use of PIF routines and the sprintf function is optional. You may write 
interpreters without them if you choose. 


A PI that wants to use the PIF routines or the sprintf function makes one call to 
the initialization function pif_init each time it is called for a new frame. The PIF 
routines then maintain an offset from the DLC header, called the PIF offset, 
which is used to extract data in various forms. The PIF offset is stored in the 
global variable pif_offset. You can use pif_offset as the offset to pass to 

get_int line if it is convenient. The offset is declared in the file PI.H. 


There are three general classes of PIF routines: 


¢ Routines that return a data item to the caller begin with pif_get_. The 
PIF offset is not updated. These routines may be used to extract data for 
either the summary line or the detail view. 


¢ Routines that display a data item on a line in the detail view begin with 
pif_show_. The PIF offset is incremented by the length of the data item 
and thus points to the next item. 


e Other miscellaneous PIF functions. 


Figure 1-3 presents a summary of the available PIF routines. 
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pif_init 
pif_save 
pif restore 


pif_get_byte 
pif_get_word 
pif _get_word_hl 
pif_get_long 
pif _get_long_hl 
pif _get_ascii 
pif _get_ebcdic 
pif_get_lstring 
pif _get_addr 


pif _show_byte 

pif show_word 
pif_show_word_hl 
pif show_long 
pif_show_long_hl 
pif _show_2byte 

pif _show_4byte 

pif _show_6byte 

pif _show_nbytes_hex 


pif _show_ascii 
pif _show_ebcdic 
pif show_lstring 


pif _show_flag 

pif show_flagbit 
pif_show_flagmask 
pif show_date 


pif show_space 
pif header 
pif trailer 
pif_autoscroll 


pif_line 


pif set 
pif skip 


Initialize PIF global variables. 
Save PIF info before calling an embedded PI. 


Restore 


PIF info after calling an embedded PI. 


Get value of a single byte. 

Get value of 2-byte word in low-high order. 
Get value of 2-byte word in high-low order. 
Get value of 4-byte word in low-high order. 
Get value of 4-byte word in high-low order. 
Get ASCII characters into aC string. 

Get EBCDIC characters into aC string. 

Get a length/string into aC string. 


Get the 


Display 
Display 
Display 
Display 
Display 
Display 
Display 
Display 
Display 


Display 
Display 
Display 


address of the current field. 


a single byte. 

2-byte word in low-high order. 
2-byte word in high-low order. 
4-byte word in low-high order. 
4-byte word in high-low order. 
2 one-byte fields. 

4 one-byte fields. 

6 one=-byte fields. 

an n-byte field in hexadecimal. 


a string of ASCII characters. 
a string of EBCDIC characters. 
a length/string of ASCII characters. 


Initialize to display bits of a flag byte. 


Display 
Display 
Display 


Display 
Display 
Display 


flag bit values. 
flag bit value if it matches the mask. 
a date and a time. 


a blank line 
a detail view header message. 
a detail view trailer message. 


Set detail view autoscroll point to be the 
next header. 

Return a detail view line buffer and advance 
the pointer. 


Set the 


PIF offset. 


Move the PIF offset backwards or forwards. 


Figure 1-3. PIF Routines. 


Calling the PIF Routines 


This section describes the calling sequences of the functions listed in Figure 1-3. 


The following initializes the PIF variables. pif_init must be called by the PI 
before any other pif_xxx routines or the sprintf function can be used. 


pif_init (pi_data_your_protocol, p, len) 
pi_data *pi_ data_your_protocol; 


*p; 
len; 


/* Initialize PIF globals */ 

/* Protocol interpreter’s control block ptr */ 
/* Start of frame data to interpret 

/* Length of frame data 
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The following saves the PIF variables before calling an embedded PI. The caller 
supplies a “pif_info” area (defined in the file PI.H) into which the current state 
information is saved. The pif_restore routine restores the state information. 


void pif save (&pd) /* save pif variables * / 
struct pif_info pd; /* Area used to save pif state */ 


The following restores the PIF variables. The caller supplied a “pif_info” area 
that was previously supplied to pif_save. 


void pif restore (&pd) /* restore pif variables * / 
struct pif _info pd; /* Area used to restore pif state * / 


It is necessary to use pif_save and pif restore only if you are calling embedded 
PIs and you wish to generate more detail view lines after the embedded 
interpreter has returned. 


The sequence below returns a byte, word (2 bytes), or longword (4 bytes) from 
the frame data at the current PIF offset plus the (signed) value of delta. The PIF 
offset is not changed. The “_hl” versions are for multibyte fields stored with the 
most significant byte first. These are macros defined in the file PI.H. 


pif get byte (delta) 
pif _get_word (delta) 
pif _get_word_hl (delta) 


pif_get_long (delta) 
pif get_long_hl (delta) 
delta; 


This sequence moves a printable ASCII null-terminated string at the current 
offset in the frame to a C string. Unprintable characters are replaced with the 
character “.”. The destination string ends with a “null” even when the source 
does not. The returned value is a pointer to the end (null) of the destination 
string. The PIF offset is not changed. 


 *pif get_ascii (offset, len, result_str) /* get asciiz string */ 
offset; /* offset to string from current pif offset */ 


len; /* maximum number of source bytes */ 
result _str[]; /* destination string * / 


The following translates a printable EBCDIC null-terminated string at the 
current offset in the packet into ASCII and moves it to a C string. Unprintable 
characters are replaced with the character “.”. The destination string ends with 
a “null” even when the source does not. The returned value is a pointer to the 
end (null) of the destination string. The PIF offset is not changed. If the user 
forces ASCII display, this calls pif_get_ascii instead. 
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*pif get_ebcdic (offset, len, result_str) /* Get ebcdic string 
offset; /* offset to string from current pif offset 


len; /* maximum number of source bytes 
result_str[]; /* destination string 


The sequence below moves an ASCII null-terminated Istring from the current 
offset in the packet to a C string. An Istring starts with a length byte followed by 
that number of characters. Unprintable characters are replaced with the 
character “.”. The destination string ends with a “null” even when the source 
does not. The returned value is a pointer to the end (null) of the destination 
string. 


*pif get_lstring (offset, result_str) © /* Get Lstring 
offset; /* Signed offset from current position 


result_str[]; /* Return ASCIIz string here 


The following line returns a pointer to the field that is at the current PIF offset. 
This is a macro defined in the file PH. 


*pif get_addr () /* return the data address ef 


The following sequence creates new lines in the detail view with the text given 
in prstr and the indicated data from the frame. The text should contain a sprintf 
formatting code, such as %d or %x indicating where the value should be 
printed. 


For the longword displays, the formatting code should be %ld or %lx. For 
pif_show 2byte, pif show 4byte, and pif_show 6byte there should be 2, 4, and 6 
formatting codes, respectively. For pif_show_nbytes_ hex, there should be a single 
%os formatting code. The value of byte_count specifies the number of bytes to 
display, from 1 to 99. The PIF offset is updated. The byte, word, and long 
routines return the displayed value. 


pif_show_byte (prstr) 

pif_show_word (prstr) 

pif_show_word_hl( prstr) 

pif_show_long (prstr) 

pif_show_long_hl (prstr) 

pif_show_2byte (prstr) 

pif_show_4byte (prstr) 

pif_show_6byte (prstr) 
pif_show_nbytes hex (prstr, byte count) 
*prstr; /* A sprintf control string 
n; : 


The following creates a new detail line from ASCII text starting at the current 
offset. The caller provides a sprintf control string whose embedded %s is 
replaced with the ASCII string copied from frame data using pif_get_ascii. The 
PIF offset is updated. 
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void pif show_ascii (len, prstr) /* Show ASCII text 
int len; /* Number of bytes to display 


char *prstr; /* control string with embedded %s 


The following creates a new detail line from EBCDIC text, starting at the current 
offset. The caller provides a sprintf control string whose embedded %s is 
replaced with the EBCDIC string copied from frame data using pif_get_ebcdic. 
(If you force ASCII translation, this calls pif_show ascii instead.) The PIF offset 
is updated. 


void pif show_ebcdic (len, prstr) /* show ebcdic text */ 
int len; /* number of bytes to display * / 


char *prstr; /* control string with embedded %s * / 


The following creates a new detail line from an ASCII Istring, starting at the 
current offset. An string starts with a length byte followed by that number of 
characters. The caller provides a sprintf control string whose embedded %s is 
replaced with the string copied from frame data using pif _get_lstring. The PIF 
offset is updated. 


void pif show_lstring (prstr) /* show lstring * / 
char *prstr; /* control string with an embedded %s */ 


The routine below displays the value of a byte with bit flags and sets up the 
correct information for subsequent calls to show flagbit and show flagmask. The 
PIF offset is incremented by 1. 


void pif _show_flag (prstr, mask) /* show flag byte */ 
char *prstr; /* title string: “ = %d” is automatically added */ 


char mask; /* mask value indicating which bits to display * / 


The routine below writes a field in the form ”....1... <string>,” indented as 
appropriate for the previous pif_show flag call. If the falsestr is NULLP, the 
truestr is used for both cases. This returns TRUE if any of the specified bits were 
on. 


boolean pif _show_flagbit (bit, truestr, falsestr) /* show flag bits */ 
char bit; /* Bit mask for 1 or more bits * / 
char truestr[]; /* string to show if any masked bits are on */ 
char falsestr[]; /* string to show if all bits are off */ 


See Also 
pif_flag_w (char*, ushort) 
pif_flag_w_hl (char*, ushort) 


The sequence below writes a detail line for a bit field only if the masked bits are 
a specified value. The line is written in the same format as for pif_show flagbit. 
This returns TRUE if the flag bits were the specified value and the line was 
written. 
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boolean pif show_flagmask (maskbits, value, prstr) /* conditional show flags */ 
char maskbits; /* Only check these bits * / 
int value; /* Check for this value */ 
char *prstr; /* Write this string if matched * / 


See also 
pif _flagbit_w 
pif_flagbit_w_hl 


The following creates a new detail line from the text given in prstr, with the %s 
replaced with a readable date and time such as “13-May-90 11:47:13”. The date 
and time are taken from a 4-byte integer at the current PIF offset representing 
the number of seconds since 1/1/90 at midnight. The integer should be stored 
with the most significant byte first for pif_show date hl and with the least 
significant byte first for pif_show date. The PIF offset is incremented by 4. 


void pif _show_date (prstr) /* show Unix-style date 
void pif _show_date_hl (prstr) /* show Unix-style date 


char *prstr; /* control string with embedded %s */ 


This call writes a blank line to the detail view. 


void pif _show_space () /* display a blank line */ 


The following outputs a header line to the detail view in the format “----- 
header _text ----- ”, followed by a blank line, and highlights data starting at the 
current PIF offset for the length specified. This routine does not update the PIF 
offset but saves the header string in the global called header_msg so other routines 
can use it. 


pif header (len, header string) /* Write a header line */ 
len; /* Length of area to highlight * / 


*header_ string; /* Header string * / 


This call outputs a trailer line to the detail view that reports on how much of the 
frame data was used by the interpreter, based on the final position of the PIF 
offset. This routine uses the header string saved by pif_header. 


void pif _trailer () /* write a trailer line */ 


The call below makes the next header line written to the detail view with 

pif header be the one that is scrolled to the top of the detail view when the user 
highlights the PI’s summary line. This is necessary only if the next header line 
is not the first for this PI. | 


void pif _autoscroll () /* set autoscroll position * / 


The following calls get_int_line to return a pointer to a detail line area. The 
caller passes a length that causes the specified number of bytes (at the current 
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PIF offset) to be highlighted in the hex view. The PIF offset is advanced by the 
number of bytes specified. Possible side effects may result if you use this as the 
first argument to sprintf; no other arguments should depend on the PIF offset. 


char *pif line (len) /* get detail line pointer * / 
int len; /* Number of bytes to highlight and advance */ 


The following sets the PIF offset to point to the specified address. This is a macro 
defined in the file PI.H. 


| void pif _set (address) /* set the PIF offset * / 
char *address; 


The following adds the signed delta to the current PIF offset. This is a macro 


defined in the file PI.H. 

void pif skip (delta) /* move the PIF offset * / 

int delta; 
The call below returns a pointer to the data item at the current PIF offset. This is 
a macro defined in the file PI.H. 

char *pif get_addr () /* return frame data address * / 


Sprintf Function in the PI Development Kit 


The sprintf function delivered with the PI Development Kit (“PDK sprintf”) has 
a number of enhancements. This section assumes that you are familiar with the 
standard sprintf routine. 


PDK sprintf will not write beyond the end of detail and summary lines. If PDK 
sprintf comes to the end of a summary or detail line and has more to print, it 
ends the line with an ellipsis and sets the value of the global variable 
sprintf_error to LINE OVERRUN. (If this has not happened, then the value of 
sprintf_error is FALSE.) If you use the PDK sprintf routine to write to summary 
and detail lines, you need not concern yourself with overrunning these lines. 


PDK sprintf understands the following format conversions: 


{<} {X} 
% [~] £€{°}] €-] (+) € 1 (#] £0] C{n}] (-{n}] (r] ({1}] {ce} 
{>} : 1*t ae {k} 


The flags must appear in the order shown above. The flags and format 
conversions are listed in Figure 1-4, along with an indication of whether each is 
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new with PDK sprintf or whether it is standard. The new PDK flags are 
discussed in the sections that follow. 


Do not print the format conversion. 
Print a value from the frame; move the PIF offset back 


Print a value from the frame; leave the PIF offset 
unchanged 


Print a value from the frame; advance the PIF offset 


> 


- Sid Left justify in the print field 


+ Std Precede a positive numeric value with a + 
<sp> Std Precede a positive numeric value with a space 
Ph Std Precede hexadecimal and octal values with Ox and 0, 
respectively 
0 Std Fill leading areas with O's rather than spaces 
<no> Std “Width” 
<no> Std “Precision” 


The value to print is in high-to-low byte order. 


Zz 
@ 
i 


| Std The value to print is four bytes long. 

k New The value to print is one byte long. 

u Std Unsigned value 

O Std Octal value 

x Hexadecimal value (use lower case a...f) 
d Std Decimal value 

b Std Binary value 

X Std Hexadecimal value (use upper case A...F) 
Cc Std Character 

Ss Std Null-terminated string 


Figure 1-4. PDK flags. 


Sprintf: Printing Values From the Frame (<, *, and > Flags) 


The *, >, and < flags tell PDK sprintf to print a value from the location in the 
captured frame pointed to by the PIF offset (rather than from its own 
parameters). See the section “The Protocol Interpreter Formatting Routines” on 
page 1-10 for information about the PIF offset. This saves copying data from the 
frame to temporary variables before calling sprintf or using pointers into the 
frame. 
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Sprintf checks that values fetched from the frame were actually captured. If the 
PIF offset points off the end of a captured frame, then PDK sprintf prints “--- 
Frame too short” in place of the formatted value. If this happens, sprintf returns 
to the Sniffer analyzer core code instead of to your PI. You must call pif_init to 
initialize the PIF offset before using these flags. 


The > flag reads a value from the frame and advances the PIF offset (similar to 
apif_get_ routine). For example: 


summary line += sprintf (summary_line, “NR=%>d"); 


reads two bytes from the frame, prints the integer value represented by the two 
bytes, and adds two bytes to the PIF offset. If NR, NS, and Length follow one 
another in the frame, then 


summary line += sprintf (summary_line, “NR=%>d NS=%>d Len=%>d”) ; 


prints each of them. The width and precision specifiers are ignored for the 
purposes of advancing the PIF offset. 


The * flag prints the value from the location in the frame but does not change 
the value of the PIF offset. This is useful for printing a value more than once. For 
example: 


detail _ line += sprintf (detail_line, “User key = %*d (%>04x)”); 
prints a line such as 
User key = 79 (004f£) 


Since the %“d format does not advance the PIF offset, the %>04x format prints 
the same value in the different format. 


The < flag prints the value from the location in the frame and then moves the 
PIF offset back through the frame. For example, if NS appears before NR ina 
frame, you can position the PIF offset to point at NR and then use this statement: 


summary line += sprintf (summary line, “NR=%<d NS=%“d”); 


Sprintf: Skipping a Value in the Frame (~ Flag) 


The ~ flag causes PDK sprintf not to print the output from the format 
specification. This is equivalent to the pif_skip function. For example: 


summary line += sprintf (summary_line, “NR=%>d %~>d NS=%“d"”); 


prints the first two-byte integer in the frame, skips the second, and then prints 
the third, and 


sprintf (summary line, “%~>s”); 


skips past the null that terminates a string without printing the string. 


(Roy) 1-19 


Protocol Interpreter Development Kit 


Sprintf: Controlling Numeric Values (r and k Flags) 


The k (“kharacter”) flag tells PDK sprintf that the next value is only a byte. For 
example: 


summary line += sprintf (summary_line, 
“Dst port=%>02kx Sre port = %>02kx”); 


‘prints port numbers from the frame that are only one byte long. 


_ Ther (“reverse”) flag tells PDK sprintf that the bytes ina two- or four-byte value 
are in “reverse” order (high-order byte first, low-order byte last, the reverse of 
the normal Intel format): 


sprintf. (detail line, “Network number = %*08r1x”); 


prints a network number for which the high byte was transmitted first, and the 
low byte was transmitted last. 


Adding Symbolic Names to the Name Table 


When your PI is called and do_names in the PI data structure is true, you must 
examine the frame for an embedded name. If you find one, add it and its 
symbolic equivalent to the station name table by calling the function 
add_station_name, as follows: 


add_station_name (flagstype, length, addr, name) 
int Fiagueypey The type of the address plus option flags; see PI.H for definitions. 
| Example: ADDRTYPE_DLC plus ASN _NOREPL indicates that the address is a 


data-link level address and that its symbolic name is not to replace a 
symbolic equivalent already assigned to that address in the name table. 


int length; The length of the address, from 1 to 16 bytes. 
char *address; A pointer to the binary station address for this name. 
char *name; A pointer to the ASCII name to enter in the table; 1 to 31 characters 


(including a final null). 


Since names discovered in the protocol data may be transitory, you should use 
ASN_NOREPL. In this way, when the names file already supplied a symbolic 
equivalent for the address, the name you find does not replace it. 


Declaring Embedded Addresses 


Each frame has source and destination DLC-level addresses associated with it 
by the Sniffer analyzer. If a PI knows of other addresses associated with this 
frame, such as Internet addresses embedded within the frame data, it may 
announce those addresses by calling the following routine: 


add_frame_addr (flagstype, length, addr) 


int  flagstype; The type of the address plus AFA_XXX option flags; see PI.H for definitions. 
| Example: ADDRTYPE_IP plus AFA_SRC for a TCP/IP internet source address of 
this frame. 
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int length; The length of the address, from 1 to 16 bytes. 
Example: 4 for TCP/IP internet addresses. 
char *address; A pointer to the binary address. 


Displaying Symbolic Names 


If you want to include the symbolic name corresponding to an address in the 
text of a summary or detail line, you may use the following routine to look up 
and format names from the current name table: 


char *format_addr (line, length, addr, flagstype) 


char *line; The address of a character buffer into which the formatted name is placed. 
The function return value is the address of the null at the end of the string. 

int length; The length of the address, from 1 to 16 bytes. Example: 6 for DLC-level 
addresses. 

char *address; A pointer to the binary address to be looked up in the name table. 

int flagstype; The type of the address plus FMT_XXX option flags; see PI.H for 


definitions. Example: ADDRTYPE_DLC plus FMT_BOTH for a DLC address to be 
formatted with both the hex value and the symbolic name. 


Adding Summary Line Flags 


If you want to create special flags and to have the Sniffer analyzer flag frames 
and display the flags in the summary view, you can call the following function: 


void add_frame_flags(str) 


char *str; Characters to add to the flags 


At most, six flag characters can be displayed for each frame. (See the section 
“About the Flags Display Option,” in the Sniffer Network Analyzer Operations 
Manual.) 


Using Other Protocol Interpreters 


In general, any protocol interpreter can call any other by using the calling 
sequence described in the section “Calling Conventions for Protocol 
Interpreters” on page 1-7. The calling protocol interpreter must supply a 
pointer to the beginning of the embedded protocol's data and the number of 
bytes remaining in the frame from that point. 


In most cases, the PI that you write will be at the top of the protocol stack, and 
the only other protocol interpreters you call will be your own. In this case, you 
can use any calling sequence you want. 


You also may call an existing NGC-written protocol interpreter if your protocol 
interpreter discovers a protocol that it interprets as embedded within your 
protocol. To find the list of NGC-written protocol interpreters, you can examine 
the REGISTER lines in the file INITPI.C. You can force any protocol interpreter 
whose registration includes the flag PITYPE_FORCEE using the pointer to that 
function. For example, since the line: 
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REGISTER (SMB, smb, “SMB”, “SMB: ", 
PITYPE_EMBEDDED+PITYPE_FORCEE+L7, 0, &no_demux) 


contains the PITYPE_FORCEE flag, you can call the smb protocol interpreter as 
follows: 


if (piptr_smb) 
smb_bytes interpreted = piptr_smb (frame_ptr, frame_length) ; 
else Ske 


Testing that piptr_smb is not NULLP ensures that this protocol interpreter has 
really been registered at run time. The name of this pointer is always “piptr_” 
followed by the second parameter on the REGISTER line in INITPI.C. What 
your protocol interpreter does if the embedded protocol has not been registered 
is up to you. 


Consider the “sample” protocol that has simple fixed-format data: 


[1 byte] Device number. 


[1 byte] Command type 
[2 bytes] Number of segments 
[20 bytes] Name of owner (null-terminated ASCII) 


In a new module, you would write your PI with a structure similar to Figure 
1-5. 


Several frames with this sample protocol embedded over SAP 0x91 (or 
ARCNET system ID 0x91) are in the capture file SAMPLE.xxC that is delivered 
with the PI Development Kit. You can build a Sniffer analyzer that contains the 
sample PI and interpret these frames by following the directions in the section 
“Building a New Sniffer Analyzer” on page 1-31 to integrate the sample PI over 
a SAP or over an ARCNET system ID. 


#define 
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USE PIF 1 /* should we use the PIF routines? */ 


#include “pi.h” 


extern struct pi_data *pi_data_sample; /* our PI data */ 


struct sample_header { /* the format of our frame data */ 
char device; 
char command; 
int nsegments; 
char owner [20]; 
}; 
int interp_sample (header, length) /* our sample interpreter */ 
struct sample_ header *header; /* pointer to our protocol header */ 
int length; /* length of the remaining data */ 
{ 
if (pi_data_sample->do_sum) { /* summary line wanted? */ 
sprintf ( 
get_sum_line (pi_data_sample), /* get a line buffer */ 
“SMP Device = %d, Cmd = %02X”, 
header->device, header->command) ; 
} /* end of summary line */ 
if (pi_data_sample->do_ int) { /* detail lines wanted? */ 
#if USE_PIF /* show how to use PIF routines */ 


#else 


/* Set up PIF globals */ 
pif_init (pi_data_sample, header, length); 


/* Output the header line and highlight the whole header. 
Note that pif _header() does not alter the PIF offset. */ 


pif header (sizeof (struct sample header), 
“Sample protocol data area”); 


/* Display the fields. Each routine advances the buffer pointer 
past the data item just displayed. */ 


pif_show_byte (“Device number = %d”); 

pif _show_byte (“Command type = %02X”); 

pif_show_word (“Number of segments = %d”); 

pif_show_ascii (20, “Owner = %s”); 

/* Write out “End of. .” message & check for excess or missing data */ 


pif_trailer (); 


/* Do detail without PIF routines */ 


Figure 1-5. Sketch for structure of a new protocol interpreter (continued on next page). 
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sprintf ( 
get_int_line (pi_data_sample, get a line buffer */ 
(char *)&header->device - dlc_header, highlight offset */ 
2% : highlight length */ 
“Device number = %d, command type = %02X”, 
header->device, header->command) ; 
sprintf ( 
get_int_line (pi_data_sample, get a line buffer */ 
(char *)&header->nsegments - dic_header, highlight offset */ 
2) highlight length */ 
“Number of segments = %d”, 
header->nsegments ) ; 


sprintf ( 
get_int_line (pi_data_sample, get a line buffer */ 
(char *)header~>owner - dic_header, highlight offset */ 


20), highlight length */ 
“Owner = %208s”, 
header->owner ); 
#endif 
} /* end of detail lines */ 


/* If there were any embedded protocol after our header, 
we could call the interpreters here. */ 


return length; /* say that we used up all the data */ 
} 


/* end of sample.c */ 


Figure 1-5. Sketch for structure of a new protocol interpreter (continued from previous 
page). 


Dependencies on Other Frames 


= Note: Although the pi_get frame and pi_invoke pis functions are still available 

for compatibility with protocol interpreters written for previous versions of the 
Sniffer analyzer, they are no longer documented, as NGC does not encourage 
their use. The mechanisms NGC recommends for dealing with dependencies on 
other frames are discussed in this section. 


In many protocols, the interpretation of a frame depends upon information 
found in other frames. Here are two examples: 


¢ When a protocol interpreter sees a frame containing a call to a server, 
the details of the call may be required to interpret the subsequent return 
frame. 


¢ When a protocol interpreter sees a client port communicating with a 
well-known server port or obtains some other clue about what 
protocols are embedded in frames to and from that client port, this 
information can help the PI interpret subsequent frames from or to the 
client port. 


After a new capture, when a new data file is loaded, and when the user chooses 
the “Re-interpret” option on the display menu, the Sniffer analyzer performs a 
“prescan” during which it interprets all the frames in order. After the prescan, 
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your PI may be called to interpret the frames in an arbitrary order, depending 
upon what the user requests to display. The prescan is an opportunity for your 
protocol interpreter to save any information it may need to be able to interpret 
the frames later out of order. 


The global variable do_prescan is TRUE when the frames are being interpreted in 
order for the first time and FALSE after this first pass has been completed. When 
do_prescan is FALSE, protocol interpreters should rely entirely upon the data in 
the frames and whatever data they stored when prescan was TRUE. 


The Sniffer analyzer maintains 16 bytes of “context” with each frame, a 
permanent data structure attached to the frame. During the prescan, your 
protocol interpreter should store enough data in the context that it can interpret 
the frame later without reference to other frames. Since the 16 bytes of context 
must be shared by all the protocol interpreters working on a frame, you should 
store as little data as possible. 


The Sniffer analyzer core code contains two library functions, one to add data 
to a frame's context and one to retrieve that data: 


typedef char * CONTEXT _DATA; 
CONTEXT_DATA *allocate_context_data (int pi_number, unsigned context_length) 


CONTEXT_DATA *fetch_context_data (int pi_number) 


The pi_number parameter for both of these functions is a number to identify your 
protocol interpreter. It is a number between 1 and 31, and it must be different 
from the numbers used by other protocol interpreters. The file PI.H contains 
definitions of constants named “CTAG_” followed by a protocol name, which are 
the pi_numbers that NGC has used for its protocol interpreters. You may use any 
other pi_numbers for your protocol interpreters. 


allocate _context_data returns a pointer to memory allocated for your frame 
context for the frame currently being interpreted. The buffer's length will equal 
context_length. If previous context data was stored for this frame with this 
pi_number, it is deleted by this call. If there is not enough space in the context to 
satisfy the request, this function returns NULLP. You may write any data you 
like into the context memory area. 


fetch_context_data returns a pointer to the data previously stored by your 
protocol interpreter for the frame currently being interpreted. If no context data 
has been stored for the current frame, then this function returns NULLP. It is up 
to you to interpret the data in the context. 


An example of the structure of a protocol interpreter that depends upon other 
frames is shown in Figure 1-6. | 
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/* Protocol interpreter that uses the context */ 
/* This array of structures is used during the prescan to store temporary data */ 
static struct { 


} prescan data [...]; 


/* This variable tells when data should be captured for prescan_data */ 
extern int do_prescan; 


/* This is the PI data structure */ 
extern struct pi_data* pi_data_user_ protocol; 


int interp_user_ protocol (frame_ptr, frame_length) 

char *frame_ptr; /* Frame to interpret */ 

int frame_length; /* Bytes in frame to interpret */ 
{ | 

CONTEXT DATA *context; 

if (do_prescan) 


/* This is the chance to save data in the array */ 
if (<this frame has information we should save>) 


<Add information to prescan_data> 


if (<data in the prescan_data array contains information 
that will be useful later in interpreting this frame>) 


{ 
if (context = allocate_context_data (CTYPE_USERPI, <length>) 


{ 
/* Got the context buffer */ 
<Copy data for later use into context>; 


if (<the data item in the prescan_data array will 
no longer be useful>) 
<Delete the item in the prescan_data array>; 


} 


/* The prescan is over. Therefore, the prescan data is */ 
/* no longer valid; erase it. */ 
/* <Note that prescan_data has no valid data>; */ 


else 


if (pi_data_user_protocol->do_sum) 


context = fetch_context_data (CTYPE_USERPI); 
<If context is not NULLP, use the information to help 
write out the summary line.> 


} 
if (pi_data_user_protocol->do_int) 
context = fetch_context_data (CTYPE _USERPI); 


<If context is not NULLP, use the information to help 
write out the detail lines.> | 


} 


Figure 1-6. Using the Frame Context. 
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Integrating into Existing Sniffer Analyzer Code 


In order for your PI to be of any use, the Sniffer analyzer core code must call 
your PI at the appropriate times. 


If you have written a protocol interpreter for a new demultiplexed 
protocol (one that is identified by an Ethertype, DSAP or ARCNET 
system ID), then registering the protocol as described in the next section 
will cause your PI to be called whenever your protocol's Ethertype, 
DSAP or ARCNET system ID appears in a frame. 


If you want to extend the interpretation of Token Ring NetBIOS frames, 
you can insert the code for your protocol interpreter into the module 
INTNETBO.C, which is provided in the PI Development Kit. The 
routine interp netbios other is called whenever the NetBIOS interpreter 
finds a frame that is not an SMB frame. 


To extend the Xwindows protocol interpreter, you can add code to the 
stub functions in the file XWINEXT.C. These routines are called 
whenever the Xwindows protocol interpreter discovers information 
that it cannot interpret. Instructions for modifying these routines is 
found in the comments in the source code. 


To extend the SMB protocol interpreter, you can write new code into 
the stub interpreter contained in the file INTSMBO.C. This PI is called 
whenever the standard SMB protocol interpreter discovers information 
that it cannot interpret. This module contains a real protocol interpreter, 
and you can write code into it just as you might write a new protocol 
interpreter. You should also consider registering the smb_other protocol 
interpreter in the file INITPI.C. 


If you have written a protocol interpreter for a new protocol running 
over AppleTalk's DDP, then adding your protocol's DDP type to the 
table that the existing DDP protocol interpreter uses will cause your PI 
to be called whenever your protocol's DDP type appears in a frame. The 
table is contained in the module AT_PORTS.C, which is provided in the 
PI Development Kit. Sample additions have been made under the 
constant USERPI OVER _DDP. 


If you have written a protocol interpreter for a new protocol running 
over TCP, IP, or UDP, then adding your protocol's port or number to 
the tables that the existing TCP, IP, and UDP protocol interpreters use 
will cause your PI to be called appropriately. 


The tables are contained in the module TCPPORTS.C, which is 
provided in the PI Development Kit. Sample additions have been made 
to this file under the constants USERPI_OVER_IP, USERPI OVER TCP, and 
USERPI_OVER UDP. The first two parameters in the TCP table are the 
minimum and maximum port; for a customer-written PI the last three 
parameters should always be “&piptr_none, 0, FALSE.” 
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¢ If you have written a protocol interpreter for a new protocol running 
over X.25, then adding your protocol to the table in the file 
X25CALLS.C will cause your PI to be called whenever your protocol's 
identification number appears in a frame. Sample additions have been 
made under the constant USERPI_OVER X25. The definition of the structure 
in X25CALLS.C is in the file X25.H. 


¢ Ifyou have written a protocol interpreter for a new protocol running 
over HDLC or HDLC framing, then adding your protocol to the table in 
the file USERHDLC.C will cause your PI to be called. 


¢ If you want to replace or partly replace a NGC- written demultiplexed 
protocol, you can arrange that the Sniffer analyzer core code calls your 
Pl instead of NGC’s. To do this, find the registration line for NGC’s PI. 
See the section, “Registering Protocol Interpreters” on page 1-28. 
Change the registration line to register your PI instead. 


If you want, your new PI can interpret only certain kinds of frames. You 
can re-register NGC’s PI as an embedded protocol and call it in 
situations where you want the NGC PI to interpret the frame. You can 
also split the work in other ways. For example, your PI can create the 
summary line, then set do_sum to FALSE in the NGC PI's data structure, 
and call the NGC PI to produce detail lines and call further embedded 
Pls. See the example in the section “Example: Changing the TCP 
Summary Line” on page 1-32. | 


Registering Protocol Interpreters 


1-28 


Each PI should be registered in the file INITPLC. Registration serves two 
purposes: 


¢ Fora demultiplexed PI, registration tells the Sniffer analyzer when it is 
appropriate to call that PI. Registration is required for a demultiplexed 
PI; otherwise, the PI is not called. 


¢ For any PI, registration causes the name of the PI to appear on the 
display filter menu so that the user can select frames that contain your 
protocol. You can choose to have your protocol to appear on the 
protocol forcing rules menu if you wish. 


All registration occurs in the function INITPI.C, which is called when the Sniffer 
analyzer is initialized. 


The macro that registers a PI appears as follows: 
REGISTER (DEFAULT, prot_name, menu_name, pi det, pi_type, ntypes, types) 


This macro must not end with a semi-colon. 
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The function that registers a PI has the following calling sequence: 


DEFAULT 


char *prot_name 


char *menu_name 


char *pi_ det 


int pi_type 


Network 


ARCNET: 


Token ring, Ethernet, 
StarLAN and PC 
Network: 


Ethernet, StarLAN or 
PC Network: 


Any: 


A flag to indicate the protocol suite to which this protocol 
interpreter belongs. All customer-written PIs should be 
registered with this flag set to “DEFAULT”. Setting this to 
any other value (or changing the values in existing 
REGISTER statements) may cause the Sniffer analyzer to 
crash. 


The name of the protocol that your PI interprets. The 
entry point to your PI must be named interp <prot_name>; 
the protocol interpreter data structure used by your PI 
must be named pi_data_<prot_name>. 


A pointer to the string that will appear in Sniffer analyzer 
menus to refer to your PI. This string must not exceed 18 
characters. 


A pointer to the string containing an abbreviation 
identifying your PI on lines in the detail window. To 
preserve alignment with displays produced by the Sniffer 
analyzer's other Pls, the string should be in one of the 


forms “xx:”, “xxx:”, or “xxxx:”, but you may use any 
string of up to 5 characters. 


The type of PI; see the PITYPE_XXX symbols in PI.H. The 
most common instance of pi_type are: 


Pl Type Comment 


Indicates that this protocol 

PITYPE_ARCID interpreter is system-code- 
demultiplexed over Arcnet. 
Indicates that this protocol 
interpreter is 
SAP-demultiplexed over token 

ca ai ring, Ethernet, StarLAN, or PC 
Network. 

: Indicates that this protocol 

interpreter is Ethertype- 

PITYPE ETYPE demultiplexed over Ethernet, 
StarLAN, or PC Network. 


Indicates that the protocol 
interpreted by this Pl is 
embedded within other 
protocols. 


PITYPE EMBEDDED 
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Indicates that this PI should 
appear on the menu of 
protocols that can be forced. 
Note that if you use this 
Any: PITYPE_FORCEE PITYPE, your protocol must 
follow the standard calling 
sequence described in the 
section “Calling Conventions 
for Protocol Interpreters.” 


int ntypes; The number of types that can be processed by this 
demultiplexed interpreter. For an embedded protocol, 
specify 0. Ntypes depend upon the network: 


ARCNET: The number of system codes 
Token ring: The number of DSAPs 
Ethernet, StarLAN and | The number of DSAPs or 
PC Network: Ethertypes 
int *types; An array of “ntypes” integers representing the various 


system codes, DSAPS, or Ethertypes (as appropriate to 
the network) that can be processed by this demultiplexed 
interpreter. 


For an embedded protocol, this parameter is ignored and 
should be specified as a null address. 


A number of sample registration lines have been inserted into INITPI.C. You 
should edit one of them to register your protocol interpreter. For example, if 
your Pl interprets a demultiplexed protocol with an Ethertype, then the 
registration line following the line: 


#if USERPI_OVER_ETYPE 


should be edited to register your protocol (instead of “sample”). For 
demultiplexed protocols, you must also edit (and should rename) the variables 
that control the demultiplexing: 


sample_sap (currently set to 0x91) 
sample _arcid (currently set to 0x91) 
sample etypes (currently set to 0x900 and 0x911) 


The REGISTER macro assumes that pi_data_<prot_name>, interp_<prot_name>, and 
rt_interp <prot_name> have been declared. Add these declarations to INITPII.H. 
You can add a line in that file that declares pi_data_sample, etc. 


The REGISTER macro assumes that piptr_<prot_name> has been declared. Add 
this declaration to INITPI2.H. You can add a line in that file that declares 
piptr_sample. 
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Building a New Sniffer Analyzer 


To build a new Sniffer analyzer with your new PI integrated into it, follow this 
process: 


ON To build a new Sniffer analyzer: 
Sy 1. 


Write the code for your protocol interpreter or modify the existing stub 
routines. 


Make the necessary modifications to INITPI.C, INITPI1.H, and 
INITPI2.H to register your protocol interpreter. 


Examine the OVLINK.LNK file and modify it appropriately. Required 
modifications are: 

a. If you have written a new module, then remove the pound sign 
from the line that reads “# file sample.obj” and change it to include the 
object file the compiler produced from your module instead of 
SAMPLE.OBJ. If you have written several new modules, duplicate that 
line as required to include them all. 


b. Ifyou have extended an existing protocol interpreter by editing one 
of the C modules provided in the PI Development Kit, then remove the 
pound sign from the line that includes the object file produced from that 
module. Also, insert a pound sign at the beginning of the line that reads 
module “<module_name>.cmp, <module_name>.cna.” 


Warning: The OVLINK.LNK file is the command file for the linker. Do 
not change the overlay structure of the Sniffer analyzer code, as this may 
cause it not to work. Also, do not make miscellaneous changes to this file 
based on RTLINK documentation; the version of RTLINK distributed 
with the PI Development Kit is not the commercially available one, and 
features may differ. 


Examine the BUILDSNF.BAT file and change the lines that set the 
following three variables: 


Must contain a directory on a disk that has at least 


np 2.5 Mb of free space. 


Must contain the directory on which version 6.00AX 


lib of the Microsoft libraries resides. 


Must contain the directory on which version 6.00AX 


include | of the Microsoft include files resides. 


Run the buildsnf.bat batch file with the command: 
BUILDSNF <pi_integration> [ < module > ]} 


The pi_integration parameter must be in upper case and must be one of 
the following: 
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NETBIOS 
SAP 
SMB 
TCP 
UDP 
X25 

XWIN 


For a demultiplexed PI for Arcnet. 

For an embedded PI over AppleTalk DDP. 
For a demultiplexed PI with an Ethertype. 
For an embedded PI running over IP. 

For an extension to the NETBIOS PI. 

For an embedded PI with a SAP. 

For an extension to the SMB PI. 

For an embedded PI running over TCP. 
For an embedded PI running over UDP. 
For an extension to X.25. 


For an extension to XWINDOWS. 


The module parameter is the name of a new module that you have 
written (without the .c extension). This module will be compiled. If you 
have extended existing modules but have not written one of your own, 
you may omit this parameter. 


6. Move the xxSNIFF.EXE file built by this operation to the xxSNIFF 
directory on your Sniffer analyzer (where xx is a two- letter abbreviation 
of your network type; EN for ethernet, AR for Arcnet, etc.). 


Note: Rename your existing Sniffer analyzer executable first so that you 
will still have it if your new one does not work. 


Example: Changing the TCP Summary Line 


Figure 1-7 shows how to write a capture filter for the TCP interpreter (part of 
the TCP/IP PI) in order to change the formatting of the summary line while 
generating the lines for the detail view with the standard interpreter. 
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/* file: sample2.c */ 

[RRR KKK KKK KKK KEI KIKI IKKE KKH IKKE KEKE EK KEEKEEKKEEEKEEEKEKEEKEKEEKKEEKKKKKKEKKEK 
SAMPLE2.C 

This is an example capture filter to the TCP Protocol Interpreter that changes 
the format of the summary line from that generated by the standard PI. 


>>> This is for Sniffer analyzer version 2.30, where interp tcp() is 

>>> not called indirectly by interp_ip() using piptr_tcp. 

>>> Accordingly, we intercept at the IP level instead of the TCP level; 

>>> all occurrences of “interp_ ip” are changed to “interp ip2” in initpi.c. 
HK KKK KKK IK KKK IT KI IKI TK IIIT KEK IIIA KKK KKK KEKE KR KEKaK / 


#include “pi.h” 


extern struct pi_data *pi_data_tcp; /* ptr to PI data for TCP PI */ 
extern int interp_ ip (void *, int); /* the original IP interpreter */ 


/*--- Our replacement IP interpreter. It gets control because all occurrences 
of “interp_ip” have been replaced by “interp_ip2” in initpi.c---*/ 


int interp ip2 (ip ptr, length) /* OUR REPLACEMENT IP INTERPRETER */ 
char *ip ptr; /* pointer to IP header */ 
int length; /* length of remaining data */ 
{ 
int tcp _ sumflag, bytes_used, flags; 
char *ptr, *tcp ptr; 
tcp sumflag = pi_data_tcp->do_sum; /* save TCP PI's summary flag */ 
pi_data_tcp->do_sum = 0; /* temporarily turn it off */ 
bytes_used = interp_ip (ip _ptr, length); /* call IP then perhaps TCP */ 
pi_data_tcp->do_sum = tcp_sumflag; /* put back TCP's flag */ 
if (tcp_sumflag /* if it was on, */ 
&& ip ptr [9] == 6) { /* and the embedded protocol was TCP, */ 
ptr = get_sum_line (pi_data_tcp); /* then generate our TCP summary line. */ 
tcp ptr = ip ptr + /* start of TCP header */ 
((ip_ptr [0] & Oxf) << 2); /* based on “IHL” IP field */ 
ptr = stradd (ptr, “TCP "); /* start with protocol name */ 


/* Format the summary line here. As an example, we build a line 
that contains only the keywords for the TCP flags that are set. 
If we were serious, we'd define structures for the headers and 
probably format other fields as well. */ 


flags = tcp_ptr [13]; /* the TCP flags byte. */ 
if (flags & 0x01) 

ptr = stradd (ptr, “FIN "); /* data finished flag */ 
if (flags & 0x02) 

ptr = stradd (ptr, “SYN "); /* synchronize flag */ 
if (flags & 0x04) 

ptr = stradd (ptr, “RST ”); /* reset flag */ 
if (flags & 0x08) 

ptr = stradd (ptr, “PSH ”); /* push flag */ 
if (flags & 0x10) 

ptr = stradd (ptr, “ACK "); /* Acknowledge flag */ 
if (flags & 0x20) 

ptr = stradd (ptr, “URG "); /* urgent flag */ 


return bytes_ used; 


/* end of sample2.c */ 


Figure 1-7. Example capture filter code. . 
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The LARGE memory model is used throughout the Sniffer analyzer and must 
be used by your PIs. This means that pointers are four bytes and integers are 
two bytes so that the symbol NULLP, not zero, should always be used to 
represent a null pointer. | 


Extreme care should be taken in writing PIs, especially in the manipulation of 
pointers used as targets. There is no hardware memory protection and with 
4-byte pointers, no segment address limitation; every byte in the machine is 
vulnerable to a wayward pointer. 


Be particularly careful that incorrect or even totally random protocol data will 
not cause your interpreter to overflow strings, to access invalid memory areas, 
or to loop. | 


The Microsoft Codeview debugger will not work because of the size of the - 
Sniffer analyzer executable module, but SYMDEB may work. 


Avoid the use of printf for debugging messages since the cursor is off the screen 
most of the time and the messages will not be seen. You can instead insert 
messages into the debugging window using the similarly called debug_msg 
function; use Shift-F1 to pop up the debugging window. 


You also can insert debugging messages into the detail view by using 

get _int line. If you must use printf, specify DEBUG as a command line 
parameter when invoking the Sniffer analyzer. The cursor will be left 
somewhere on the screen, but your output will destroy the screen formatting. 


Be aware of interpreting invalid information beyond the end of the stored data. 
If frames were captured in “partial frame” mode, the data present may be less 
than the entire frame; the global bytes_not_stored indicates how much data is not 
present. 


The PIF routines and the sprintf function detect when they are about to access 
locations beyond the end of the frame data. They print a frame too short 
message into the detail view, and it does not return to your PI. 


Be careful not to store more than MAX_SUM_LINE characters in a summary line 
buffer or more than MAX_INT_LINE characters in a detail line buffer, regardless of 
what the frame data might be. The PDK sprintf function protects against this 
possibility. 


The 80386 processor that is used in the Sniffer analyzer stores integers in 
low-high format. Depending on your protocol, you may have to reverse 
integers for printing or calculation. The PIF routines ending in _hl are useful in 
that case, as is the “r” flag in PDK sprintf. 


The Microsoft Version 6.00AX compiler supports argument type checking using 
ANSI standard function prototyping. The #include files provided with the PI 
Development Kit have declarations for all the documented functions, and you 
are encouraged to add declarations of your new functions. 


Programming and Debugging Hints 


The /J flag has been used to compile all modules to make the default for 
character variables unsigned. 
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On page 1—4, under the heading, “Writing a Protocol Interpreter,” the manual informs you that you will need to obtain 
Version 6.00AX of the Microsoft C compiler. This compiler and the necessary library files are now included as part of 
the Protocol Interpreter Development Kit. You no longer need to obtain them separately. 


On page 1—6, Figure 1-1 lists the files provided with the Protocol Interpreter Development Kit. In addition to the files 
listed, the following files are also provided as part of the Microsoft 6.00AX C Compiler: 


Files Provided With Microsoft 6.00 AX C Compiler 
CL.EXE | CL.MSG | CIL.EXE 
LLIBCE.LIB | C1.ERR C23.ERR 


CL.ERR | C2L.EXE | C3L.EXE 


On page 1~7, under the heading, “Installing the Microsoft C Compiler,” the document gives instructions for installing 
the compiler. The Protocol Interpreter Development Kit now includes all the tools required to write new protocol 
iiiérpreters and build new Sniffer analyzers, including the compiler and the library. You will not aced to install the 
Microsoft C Compiler because it is already installed with the Protocol Interpreter Development Kit. 


On page 1-31, Step 4 of the procedure, “To build a new Sniffer analyzer,” lists several changes that should be made to 
the BUILDSNF.BAT file. The necessary files for Microsoft C 6.00AX are now distributed with the Protocol Interpreter 
Development Kit. If you are using the compiler supplied with your Protocol Interpreter Development Kit, then the 
BUILDSNF.BAT file is already set correctly. You will not need to change the BUILDSNF.BAT file unless you are 
using a custom development environment. If this is the case, you will need to change the lines in BUILDSNF.BAT that 
set the three variables listed in Step 4 on page 1-31. 


To use the Protocol Interpreter Development Kit, you must add the following line to the CONFIG.SYS file of the 
Sniffer Network Analyzer: 


DEVICE=C: \DOS\HIMEM EXE 


Note: If your Sniffer Network Analyzer has less than 32MB of RAM, you must remove the above command line 
before starting the Sniffer Network Analyzer. 


Before using the Microsoft C compiler, type the following command: 
SET PATH=C:\DOS;C:\TOOLS: C: \TOOLS\CEZ@AXx 
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